In this tutorial, you will learn how to use OpenCV and the cv2.imread function to:

By the end of this guide, you will have a good understanding of how to load images from disk with OpenCV.

A dataset of images is essential to practice and understand the operation of the OpenCV library. It allows us to deal with images of different formats and sizes, thus broadening our understanding of how to manipulate images using OpenCV.

Roboflow has free tools for each stage of the computer vision pipeline that will streamline your workflows and supercharge your productivity.

Sign up or Log in to your Roboflow account to access state of the art dataset libaries and revolutionize your computer vision pipeline.

You can start by choosing your own datasets or using our PyimageSearch’s assorted library of useful datasets.

Bring data in any of 40+ formats to Roboflow, train using any state-of-the-art model architectures, deploy across multiple platforms (API, NVIDIA, browser, iOS, etc), and connect to applications or 3rd party tools.

To learn how to load an image from disk using OpenCV and cv2.imread, just keep reading.

In the first part of this tutorial, we’ll discuss how to load an image from disk using OpenCV and the cv2.imread function.

From there, you’ll learn how to configure your development environment to install OpenCV.

We will then review our project directory structure, followed by implementing load_image_opencv.py, a Python script that will load input images from disk using OpenCV and the cv2.imread function.

We’ll wrap up this tutorial with a discussion of our results.

To load an input image from disk using OpenCV, we must use the cv2.imread function (Figure 1).

The cv2.imread function accepts a single parameter, the path to where your image lives on your disk:

The OpenCV cv2.imread function then returns either of two values:

Typically, the cv2.imread function will return None if the path to the input image is invalid, so be sure to double-check and triple-check your input image paths! The function will also fail for unsupported image file types, although OpenCV can read a wide variety of them, including JPEG, PNG, TIFF, and GIF.

Let’s see how to obtain the OpenCV library before putting the cv2.imread function into action.

Before digging into image loading with OpenCV, you’ll need to have the library installed on your system.

Luckily, OpenCV is pip-installable:

If you need help configuring your development environment for OpenCV 4.3+, I highly recommend that you read my pip install OpenCV guide — it will have you up and running in a matter of minutes.

All that said, are you:

Then join PyImageSearch Plus today!

Gain access to Jupyter Notebooks for this tutorial and other PyImageSearch guides that are pre-configured to run on Google Colab’s ecosystem right in your web browser! No installation required.

And best of all, these Jupyter Notebooks will run on Windows, macOS, and Linux!

Let’s review our project structure. Grab the source code from the “Downloads” section, unzip the content, and navigate to where you saved it:

Our project contains a single Python script named load_image_opencv.py and a couple of test images.

In our script, we’ll first load an image from disk using the OpenCV cv2.imread function and then display it on screen for assessment. Finally, we’ll save the displayed image back to disk with OpenCV as a new file named newimage.jpg.

Let’s now implement our image-loading Python script using OpenCV!

Let’s get started learning how to load an input image from disk using OpenCV.

Create a Python script named load_image_opencv.py, and insert the following code:

Start by importing the Python utility package argparse for command line arguments parsing on Line 2 and the OpenCV library on Line 3.

Notice that the OpenCV developers adopted the name cv2 from version 2.0 of the library and kept this naming convention regardless of the release we’re using (e.g., 3.x, 4.x). We’ll be using the latest version 4.3+ installed as detailed in the previous section.

The argparse package allows us to pass dynamic arguments to our Python script such that we do not have to hardcode parameter variables that need to be manually changed every time we’d like to alter their values.

If you are unfamiliar with how the argparse package works, be sure to read my tutorial on the subject.

Lines 6-9 set up our command line argument parser with a single argument containing the path to our input --image. We set the argument as required, ensuring that a value must always be passed when invoking our Python script.

With our input --image path dynamically defined, it’s now easy to load the image using OpenCV:

OpenCV makes reading a wide range of image file types from disk a breeze with the cv2.imread function.

We load the input --image to memory on Line 13 using cv2.imread, which returns the image as a NumPy array. Upon success, we obtain the image dimensions (h, w, c) from the shape of the array (Line 14) — I’ll provide more information about caveats regarding this line of code later.

We can now print the image dimensions (width, height, and number of channels) to the terminal for review (Lines 18-20).

In a future blog post, we’ll talk about what image channels are, but for now keep in mind that the number of channels will be three for color images, representing the Red, Green, and Blue (RGB) components of pixel colors.

But hey, what good is it having an image in memory if we do not know whether it was read correctly by OpenCV? Let’s display the image on screen for verification:

The cv2.imshow OpenCV function is very convenient here, as it displays an image on our screen using only two parameters (Line 23). The first is a string representing the name assigned to the window that will be opened to hold the figure; the second is the image we want to display.

From there, we need to call the cv2.waitKey function to keep the window opened until a key is pressed (Line 24). This function receives a single parameter corresponding to the time delay (in milliseconds) used to keep the window alive if no key is pressed. The parameter value 0 instructs the cv2.waitKey function to wait indefinitely.

Finally, Line 28 saves the image back to disk. The OpenCV cv2.imwrite function accepts a filename as the first parameter and the image as the second.

The cv2.imwrite function saves a file named “newimage.jpg” that automatically converts the image to JPG format based on the filename extension.

You should now be able to apply OpenCV to:

We’ll review some of the results of those operations in the next section.

Now it’s time to load images from the disk using OpenCV!

Start by accessing the “Downloads” section of this tutorial to retrieve the source code and example images.

From there, open a terminal, and execute the following command:

For my 30th birthday a couple of years ago, my wife rented a near-replica jeep from Jurassic Park (my favorite movie) for us to drive around for the day.

In Figure 3, you can see that our input image, 30th_birthday.png, has been loaded from disk using OpenCV and then displayed to your screen.

This image has a width of 720 pixels, a height of 764 pixels, and three channels (one for each Red, Green, and Blue channel, respectively).

Additionally, if you check the contents of our project directory after running the script, you will see a file named newimage.jpg:

This image was saved to disk via OpenCV using the cv2.imwrite function.

Note that while the 30th_birthday.png image was a PNG file type, OpenCV has automatically converted the image to a JPG file type for us.

Let’s try another image:

Continuing on with the Jurassic Park theme in this tutorial, here we have a photo of Ray Arnold (played by Samuel L. Jackson).

This image has a width of 577 pixels, a height of 433 pixels, and three channels.

If you’re brand-new to OpenCV, I suggest you now take the time to play around with the cv2.imread function. Specifically, experiment with:

Speaking of that final bullet item, let’s give that a try now …

You might be wondering what happens if we pass an invalid file path (meaning the path to the input image does not exist on disk) to OpenCV and cv2.imread?

Let’s find out:

Here I am purposely providing an image path that does not exist on my disk.

When I pass an invalid image path to OpenCV’s cv2.imread function, cv2.imread returns None.

And when I try to grab the image width, height, and number of channels, Python errors out with an AttributeError, saying that the NoneType object does not have a shape attribute.

This error makes sense when you think about it:

Anytime you see these None or NoneType errors, your first step in diagnosing and resolving them is to investigate whether your image was successfully read from disk correctly. 99% of the time the error is due to your code assuming a valid image, but in fact the image was not properly read from disk!

I strongly believe that if you had the right teacher you could master computer vision and deep learning.

Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?

That’s not the case.

All you need to master computer vision and deep learning is for someone to explain things to you in simple, intuitive terms. And that’s exactly what I do. My mission is to change education and how complex Artificial Intelligence topics are taught.

If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to successfully and confidently apply computer vision to your work, research, and projects. Join me in computer vision mastery.

Inside PyImageSearch University you'll find:

Click here to join PyImageSearch University

In this tutorial, you learned how to load images using OpenCV and the cv2.imread function.

We created a Python script to:

OpenCV conveniently handles reading and writing a wide variety of image file formats (e.g., JPG, PNG, TIFF). The library also simplifies displaying an image on screen and allowing user interaction with the opened window.

If an image cannot be read by OpenCV, you should carefully check if the input filename was given correctly, as the cv2.imread function returns a NoneType Python object upon failure. The function will fail if the file does not exist or if the image format is unsupported by OpenCV.

We have also printed the image dimensions to the terminal (width, height, and number of channels), based on the values of the underlying NumPy array shape. Our script then saved the image to disk using the JPG format, taking advantage of OpenCV’s ability to automatically convert the image to the desired file type.

In the next tutorial in this series, you will learn about OpenCV image basics, including what a pixel is, an overview of the image coordinate system, and how to access individual pixel values.

To download the source code to this post (and be notified when future tutorials are published here on PyImageSearch), simply enter your email address in the form below!

Enter your email address below to get a .zip of the code and a FREE 17-page Resource Guide on Computer Vision, OpenCV, and Deep Learning. Inside you'll find my hand-picked tutorials, books, courses, and libraries to help you master CV and DL!